<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Converter Signature</title>
<link rel="stylesheet" href="../../../../../../doc/src/boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
<link rel="home" href="../../index.html" title="Chapter 1. Boost.Convert 2.0">
<link rel="up" href="../design_notes.html" title="Design Notes">
<link rel="prev" href="../design_notes.html" title="Design Notes">
<link rel="next" href="user_interface_signature.html" title="User Interface Signature">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr>
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../boost.png"></td>
<td align="center"><a href="../../../../../../index.html">Home</a></td>
<td align="center"><a href="../../../../../../libs/libraries.htm">Libraries</a></td>
<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
<td align="center"><a href="../../../../../../more/index.htm">More</a></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="../design_notes.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../design_notes.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="user_interface_signature.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="boost_convert.design_notes.converter_signature"></a><a class="link" href="converter_signature.html" title="Converter Signature">Converter
      Signature</a>
</h3></div></div></div>
<p>
        The following converter signatures have been considered:
      </p>
<pre class="programlisting"><span class="keyword">bool</span> <span class="keyword">operator</span><span class="special">()(</span><span class="identifier">TypeIn</span> <span class="keyword">const</span><span class="special">&amp;,</span> <span class="identifier">TypeOut</span><span class="special">&amp;);</span> <span class="comment">//#1</span>
<span class="keyword">void</span> <span class="keyword">operator</span><span class="special">()(</span><span class="identifier">TypeIn</span> <span class="keyword">const</span><span class="special">&amp;,</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">optional</span><span class="special">&lt;</span><span class="identifier">TypeOut</span><span class="special">&gt;&amp;);</span> <span class="comment">//#2</span>
<span class="identifier">boost</span><span class="special">::</span><span class="identifier">optional</span><span class="special">&lt;</span><span class="identifier">TypeOut</span><span class="special">&gt;</span> <span class="keyword">operator</span><span class="special">()(</span><span class="identifier">TypeIn</span> <span class="keyword">const</span><span class="special">&amp;);</span> <span class="comment">//#3</span>
</pre>
<p>
        From the design perspective the signature #1 has the advantage of providing
        the best <span class="emphasis"><em>separation of concerns</em></span>. Namely, it leaves the
        respective converter with only one task -- the actual task of conversion.
        In practice though that can result in unnecessary performance overhead. Namely,
        given an instance of <span class="emphasis"><em>TypeOut</em></span> type is supplied from outside,
        a storage for that instance needs to be allocated and, most importantly,
        initialized. That initialization phase (which can be expensive) is an unnecessary
        overhead as, if the conversion operation succeeds, the initial value is overridden
        with the actual result, if it fails, then the value of the <span class="emphasis"><em>TypeOut</em></span>
        instance is either meaningless or worse misleading.
      </p>
<p>
        The signature #2 avoids the initialization overhead by deploying <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">optional</span></code>'s ability to allocate storage
        <span class="emphasis"><em>without initializing it</em></span>. Now the storage for <span class="emphasis"><em>TypeOut</em></span>
        is still allocated outside but it is not initialized. It is now converter's
        responsibility to know <span class="emphasis"><em>how</em></span> to initialize the <span class="emphasis"><em>TypeOut</em></span>
        instance and, <span class="emphasis"><em>when</em></span> needed, to actually initialize it.
        In practice it is usually easier than it might sound. For example, <code class="computeroutput"><span class="identifier">strtol</span><span class="special">()</span></code>-based
        converter might have something along the following lines:
      </p>
<pre class="programlisting"><span class="keyword">void</span> <span class="keyword">operator</span><span class="special">()(</span><span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">str_in</span><span class="special">,</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">optional</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&gt;&amp;</span> <span class="identifier">result_out</span><span class="special">)</span> <span class="keyword">const</span>
<span class="special">{</span>
   <span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">str_end</span> <span class="special">=</span> <span class="identifier">str_in</span> <span class="special">+</span> <span class="identifier">strlen</span><span class="special">(</span><span class="identifier">str_in</span><span class="special">);</span>
   <span class="keyword">char</span><span class="special">*</span>       <span class="identifier">cnv_end</span> <span class="special">=</span> <span class="number">0</span><span class="special">;</span>
   <span class="keyword">long</span> <span class="keyword">int</span>     <span class="identifier">result</span> <span class="special">=</span> <span class="special">::</span><span class="identifier">strtol</span><span class="special">(</span><span class="identifier">str_in</span><span class="special">,</span> <span class="special">&amp;</span><span class="identifier">cnv_end</span><span class="special">,</span> <span class="identifier">base_</span><span class="special">);</span>

   <span class="keyword">if</span> <span class="special">(</span><span class="identifier">INT_MIN</span> <span class="special">&lt;=</span> <span class="identifier">result</span> <span class="special">&amp;&amp;</span> <span class="identifier">result</span> <span class="special">&lt;=</span> <span class="identifier">INT_MAX</span> <span class="special">&amp;&amp;</span> <span class="identifier">cnv_end</span> <span class="special">==</span> <span class="identifier">str_end</span><span class="special">)</span>
       <span class="identifier">result_out</span> <span class="special">=</span> <span class="keyword">int</span><span class="special">(</span><span class="identifier">result</span><span class="special">);</span>
<span class="special">}</span>
</pre>
<p>
        The signature #3 has been briefly considered as aesthetically advantageous
        and more idiomatic. Unfortunately, it lacked automatic deduction of the
        <span class="emphasis"><em>TypeOut</em></span> which, consequently, had to be specified explicitly.
        For different types of supported converters (class-based, plain old functions,
        lambdas) that complicated considerably the implementation of the <span class="emphasis"><em>Boost.Convert</em></span>
        infrastructure and restricted implementation of the respective converters.
      </p>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"></td>
<td align="right"><div class="copyright-footer">Copyright © 2009-2020 Vladimir Batov<p>
        Distributed under the Boost Software License, Version 1.0. See copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>.
      </p>
</div></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="../design_notes.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../design_notes.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="user_interface_signature.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
</body>
</html>
